Upgraded library to support most features of WM8960 I2C protocol #2

relic-se · 2024-08-13T21:19:51Z

I was eager to use SparkFun's WM8960 breakout board with a CircuitPython project, and found this unfinished library to provide a starting point to communicate with this device but otherwise lacking.

To ameliorate this problem, I've ported over the Arduino library and examples provided by SparkFun for this board (https://github.com/sparkfun/SparkFun_WM8960_Arduino_Library) with a few minor modifications:

setSampleRate to automatically configure PLL, system clock, etc for most supported frequencies (8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000)
quick configuration methods of key features: configureI2S, configureDAC, configureHeadphones, configureSpeakers
Register reset and general setup on object initialization
Stereo paired methods for most Left/Right methods to simplify operation
setPPLK uses a single integer value rather than 3 separate bytes

All examples have been tested with an RP2040 and WM8960 breakout module successfully. That is except for those involving I2S input (examples 08, 09, 11, and 15) because I2SIn/I2SInOut is not yet a feature of CircuitPython (as of 9.1.1; more info: adafruit/circuitpython#2676).

I look forward to seeing this library added to the community bundle after review (https://github.com/adafruit/CircuitPython_Community_Bundle) as I think this is a very powerful codec with a large feature set for the price and is already being used in 1 Adafruit product, https://www.adafruit.com/product/4757.

I did my best to give attribution to Pete Lewis of SparkFun, the original author of the Arduino library, under the MIT license, but there may be room for improvement.

Thank you for your consideration!

…M8960_Arduino_Library for use with CircuitPython.

…riable.

… Kurt.

…the original library.

tannewt

Thanks for the PR! It seems like this was autoconverted from the Arduino library. That's fine except you now need to curate and refine the API for Python.

Generally we don't want to expose everything. Instead, we only want the APIs we need for the examples we want to show. Your extended examples are a great place to start for this.

I've pointed out a couple things and linked to the dev guide. Please read the dev guide over and refine the API to match that.

Thanks!

CODE_OF_CONDUCT.md

pyproject.toml

adafruit_wm8960.py

relic-se · 2024-08-15T15:30:31Z

Hey Scott! Thanks for looking over this library. I think all of your suggestions so far are on the right track and I will be following your updates shortly.

The only note I'll make is that I did manually convert this library (with extensive use of find and replace, of course), which is why there might be some mistakes here and there. Though I think there is some benefit to maintaining a some compatibility with the original library, I also think it's a great idea to implement the CircuitPython methodology where possible.

However, if a tool does exist to automatically convert Arduino libraries to be compatible with CircuitPython, that would be really great!

Co-authored-by: Scott Shawcroft <scott@tannewt.org>

…s://docs.circuitpython.org/en/latest/docs/design_guide.html#use-of-micropython-const & https://docs.circuitpython.org/en/latest/docs/design_guide.html#driver-constant-naming)

tannewt · 2024-08-15T16:50:07Z

However, if a tool does exist to automatically convert Arduino libraries to be compatible with CircuitPython, that would be really great!

An LLM like ChatGPT or GitHub Copilot can do this conversion pretty well. Give it the source arduino and ask it to generate python. It may even be able to convert to properties. You'll still need to check and refine it but it makes the initial conversion much quicker.

relic-se · 2024-08-22T15:32:26Z

I've gotten around to revisiting the examples provided and narrowed them down to only 4 which I felt demonstrated unique features. If I2SInOut ever reaches the light in CircuitPython, I'll make sure to add an example which features ADC to MCU functionality. https://adafruit-circuitpython-wm8960.readthedocs.io/projects/dev/en/latest/examples.html

…fter reset.

…nd `missing-class-docstring`).

tannewt

Examples look really good. I like how readable the human friendly names are.

One comment about formatting and it looks like you are still working on adding doc strings.

adafruit_wm8960.py

…it_wm8960.WM8960`, and advanced driver class, `adafruit_wm8960.advanced.WM8960_Advanced`. Documentation completed.

relic-se · 2024-09-02T13:57:43Z

@tannewt Here's the updated library. All the documentation has been populated as far as I'm aware. It may get a bit lackadaisical here and there, but I'll leave it up to your scrutiny.

tannewt

Looks like pre-commit is unhappy. One missing space. Otherwise the comments look really good! This will be a very helpful driver for folks using this chip. Thanks!

adafruit_wm8960/__init__.py

Co-authored-by: Scott Shawcroft <scott@tannewt.org>

tannewt · 2024-09-06T20:14:58Z

I think you need to change this to fix the build issue:

Adafruit_CircuitPython_WM8960/pyproject.toml

Lines 41 to 44 in cf3620d

    
           [tool.setuptools] 
        
           # TODO: IF LIBRARY FILES ARE A PACKAGE FOLDER, 
        
           #       CHANGE `py_modules = ['...']` TO `packages = ['...']` 
        
           py-modules = ["adafruit_wm8960"]

relic-se · 2024-09-06T21:30:39Z

I think that finally does it! Let me know if there's anything else I need to check up on.

tannewt

All good! Thanks for iterating on this with me.

relic-se · 2024-09-09T21:23:50Z

@tannewt Likewise! I'm excited to start using this in my next project.

ladyada · 2024-09-11T16:11:10Z

awesome, thank you @dcooperdalrymple :)
@TheKitty newsy

relic-se added 19 commits August 13, 2024 07:18

Converted Arduino library from https://github.com/sparkfun/SparkFun_W…

59aacb4

…M8960_Arduino_Library for use with CircuitPython.

Updated copyright in documentation and minor changes.

cfd27d9

Transferred and converted examples from Arduino library.

89036d3

Reset device on initialization and copy default registers to local va…

e6b343b

…riable.

Fix bug in _writeRegisterMultiBits.

7f54800

Use single integer for value of PLLK rather than separate nibbles.

215deec

Add methods to enable/disable both channels of DAC and ADC.

4276430

Updated simpletest example to use new library.

6892379

Ported over more complex example, eighties_dystopia, by @todbot / Tod…

71c1a07

… Kurt.

Enable VREF and VMID on initialization by default.

90a9745

Paired stereo functions added.

40bb1ee

Configuration utilities for I2S, DAC, headphones, and speakers.

a368bda

Separate sample rate calculation from configuration method.

5fb70c5

Additional stereo pair methods.

4a22db3

Updated examples to use stereo pair methods.

23d81ee

Updated stereo pairing output mixer method names to better represent …

248daed

…the original library.

Fix typo in INPUT2 example.

d333550

Basic error checking and boolean response.

bb23918

Updated documentation with new examples.

ca54148

tannewt requested changes Aug 14, 2024

View reviewed changes

CODE_OF_CONDUCT.md Outdated Show resolved Hide resolved

pyproject.toml Outdated Show resolved Hide resolved

adafruit_wm8960.py Outdated Show resolved Hide resolved

adafruit_wm8960.py Outdated Show resolved Hide resolved

adafruit_wm8960.py Outdated Show resolved Hide resolved

relic-se and others added 3 commits August 15, 2024 10:47

Removed unimplemented adafruit_wm8960.WM8960.isConnected

381f022

Co-authored-by: Scott Shawcroft <scott@tannewt.org>

Fixed pyproject.toml Homepage url.

e8ea476

Updated library constants to use const() and naming conventions (http…

473b67f

…s://docs.circuitpython.org/en/latest/docs/design_guide.html#use-of-micropython-const & https://docs.circuitpython.org/en/latest/docs/design_guide.html#driver-constant-naming)

relic-se added 5 commits August 16, 2024 12:49

Revert code of conduct to original version.

ef9d64f

API updated to use property-driven standards.

e30892e

Basic examples updated to use new API.

a559078

Determine register default value automatically during initial reset.

2fa811e

Rename WMBit(s) to WOBit(s).

5eabc95

relic-se added 5 commits August 22, 2024 09:40

Add stereo function to set mic inverting input.

ed2b134

Remove "boost" from mic output attributes.

8480a43

Use monotonic value for 3D enhance depth.

3b085c8

Fix minor typing issues.

722dec4

Remove unnecessary examples and reorganize into meaningful examples..

b4d42b5

relic-se added 6 commits August 23, 2024 08:36

Added related product links.

dcd09f2

Updated usage example.

062655c

Updated formatting using black.

8811ae1

Local register list reset bug fix.

776e3bc

Ensure that registers contain address index in bytearray before and a…

bc58f1a

…fter reset.

Conform to pylint standards (excluding missing-function-docstring a…

5da5380

…nd `missing-class-docstring`).

tannewt reviewed Aug 27, 2024

View reviewed changes

adafruit_wm8960.py Outdated Show resolved Hide resolved

relic-se added 2 commits September 2, 2024 08:53

Rearranged library structure to introduce basic driver class, `adafru…

6299b2b

…it_wm8960.WM8960`, and advanced driver class, `adafruit_wm8960.advanced.WM8960_Advanced`. Documentation completed.

Updated example code to utilize basic driver.

557d8e7

relic-se added 3 commits September 2, 2024 09:07

Fix logarithmic functions.

1f968b4

Fix tuple manipulation error.

ec79c65

Updated examples to pass pylint compatibility and black formatting.

cf4f995

tannewt requested changes Sep 3, 2024

View reviewed changes

adafruit_wm8960/__init__.py Outdated Show resolved Hide resolved

relic-se and others added 3 commits September 4, 2024 14:15

Fix whitespace in class description.

7442bf8

Co-authored-by: Scott Shawcroft <scott@tannewt.org>

Fix import order in simpletest example.

86cbd8b

Fix trailing whitespace and minor formatting.

962a1a8

Updated pyproject.toml to use package folder.

5ae8bc5

tannewt approved these changes Sep 9, 2024

View reviewed changes

tannewt merged commit bba4f61 into adafruit:main Sep 9, 2024
1 check passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Upgraded library to support most features of WM8960 I2C protocol #2

Upgraded library to support most features of WM8960 I2C protocol #2

relic-se commented Aug 13, 2024

tannewt left a comment

relic-se commented Aug 15, 2024 •

edited

Loading

tannewt commented Aug 15, 2024

relic-se commented Aug 22, 2024 •

edited

Loading

tannewt left a comment

relic-se commented Sep 2, 2024

tannewt left a comment

tannewt commented Sep 6, 2024

relic-se commented Sep 6, 2024

tannewt left a comment

relic-se commented Sep 9, 2024

ladyada commented Sep 11, 2024

Upgraded library to support most features of WM8960 I2C protocol #2

Upgraded library to support most features of WM8960 I2C protocol #2

Conversation

relic-se commented Aug 13, 2024

tannewt left a comment

Choose a reason for hiding this comment

relic-se commented Aug 15, 2024 • edited Loading

tannewt commented Aug 15, 2024

relic-se commented Aug 22, 2024 • edited Loading

tannewt left a comment

Choose a reason for hiding this comment

relic-se commented Sep 2, 2024

tannewt left a comment

Choose a reason for hiding this comment

tannewt commented Sep 6, 2024

relic-se commented Sep 6, 2024

tannewt left a comment

Choose a reason for hiding this comment

relic-se commented Sep 9, 2024

ladyada commented Sep 11, 2024

relic-se commented Aug 15, 2024 •

edited

Loading

relic-se commented Aug 22, 2024 •

edited

Loading